/*
 * Copyright 2011 Helios Technologies.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.heliostech.gwt.widget.dialog.wizard;

import com.google.gwt.resources.client.ImageResource;
import com.google.gwt.user.client.ui.IsWidget;

/**
 * Encapsulate information related to a particular step in a wizard.
 * The IWizardStep interface must be implemented by steps used in BaseWizard implementation.
 * @author ldesdier
 *
 */
public interface IWizardStep {

	/**
	 * Get the named action performed in the step (i.e. something like "Create New Contact").<br/>
	 * This named action will be displayed at the top of the dialog description.
	 * @return The named action performed in that step as a String.
	 */
	public String getStepAction();
	
	/**
	 * Get the description of what needs to be done in that step.<br/>
	 * This will be displayed as the content of the dialog description.
	 * @return The step description as a String.
	 */
	public String getStepDescription();
	
	/**
	 * Get the widget that will be placed as the step content when requested.
	 * @return The step content as a Widget.
	 */
	public IsWidget getStepContent();
	
	/**
	 * Get an optional icon that depicts the step.<br/>
	 * This will be placed as the dialog description icon.
	 * @return The step icon as an ImageResource.
	 */
	public ImageResource getStepIcon();
	
	/**
	 * This method is executed when the user has clicked on the button [Next].<br/>
	 * If this method returns false the execution will stop and the step will not be displayed.<br/>
	 * If the method returns true the step will be displayed as requested.<br/>This allow the implementer
	 * to make a check for pre-condition before going forward (e.g. data validation).
	 * @return True if the step is allowed to be displayed and false otherwise.
	 */
	public boolean onBeforeNext();
	
	/**
	 * This method is executed when the user has clicked on the button [Previous].<br/>
	 * If this method returns false the execution will stop and the step will not be displayed.<br/>
	 * If the method returns true the step will be displayed as requested.<br/>This allow the implementer
	 * to make a check for pre-condition before going backward (e.g. data validation).
	 * @return True if the step is allowed to be displayed and false otherwise.
	 */	
	public boolean onBeforePrevious();
	
	/**
	 * This method is executed when the user has clicked on the button [Finish].<br/>
	 * If this method returns false the execution will stop and the finish command will not be executed.<br/>
	 * If the method returns true the finish command will be executed as requested.<br/>
	 * This allow the implementer to make a check for pre-condition before allowinf the finish process to be executed (e.g. data validation).
	 * @return True if finishing is allowed and false otherwise.
	 */	
	public boolean onBeforeFinish();
	
	/**
	 * Returns the index of the step in the wizard flow.
	 * @return The step index as an int.
	 */
	public int getIndex();
	
	/**
	 * Specifies if the Next button should be enabled or not for that step.
	 * @return True if the Next button is enabled and false otherwise.
	 */
	public boolean allowNext();
	
	/**
	 * Specifies if the Previous button should be enabled or not for that step.
	 * @return True if the Previous button is enabled and false otherwise.
	 */
	public boolean allowPrevious();
	
	/**
	 * Specifies if the Finish button should be enabled or not for that step.
	 * @return True if the Finish button is enabled and false otherwise.
	 */
	public boolean allowFinish();
	
	/**
	 * Clean the step content for later reuse.
	 */
	public void cleanup();
	
}
